This chapter discusses in detail the table objects included in the Containers Library. It describes how to use the tables and the different types of tables available.
In this chapter you will learn:
- What are tables, fields, and field structures?
- How to use tables
- The characteristics of each type of table
What are tables, fields and field structures?
Tables are stream-based sequences in which each data item has one or more fields. There are two types of tables provided in the Containers Library: TTable, which stores records, and TObjectTable, which stores objects. Each data item is analogous to a Pascal record, with the fields in the record equivalent to the fields in the table. Entire records or individual fields of a data item may be accessed. The Cursors Library provides a table specific cursor which takes advantage of the field access in tables. The field structure for the table, or listing of the order, types, and size of fields in a table, is specified on creation of the table and is static for the life of the table. In order to change the field structure you must create a new table with the desired field structure and copy the data to it. A field may be of any of the data types declared in the ctFields unit's FieldTypes constant, except ftObjectID, which is used internally.
Tables provide the "flat-file" database structure necessary for implementing most any database format. By using the TTable and TObjectTable containers, you can easily incorporate simple database tables into your applications, with support for up to 2 billion (MaxLongInt) records and 18 field types. You can also implement indexed and multi-indexed tables in your applications with very little effort, by combining the powerful indexing capabilities of B trees with a table.
Using the Tables
There are several steps in creating and using a new table:
1- Define the field structure
2- Define the stream
3- Register the field and field structure types for
stream usage
4- Initialize the table
5- Add/delete/modify data
6- Dispose the table,
7- And last, dispose the stream.
The first step in using a table is defining the table's field structure. Defining the field structure is equivalent to defining a record or object type in Pascal. The field structure should mirror the record or object structure which the table will hold. The field order, size, and data type specified in the table must match the record or object's field structure exactly, or unpredictable results will occur. Field structures use the TField and TFieldStructure objects in the ctFields unit. Field information is stored in TField's, which are stored in a TFieldStructure. Descendant objects of both types may be used.
Creating a New Table
The following shows the Pascal declaration of a record structure for an address (see TABLE1.PAS). The order of field insertion into the field structure determines the order in which the fields should occur in the corresponding record.
type
TAddressRec = record
Line1: string[50];
Line2: string[50];
City: string[50];
State: string[50];
end;
The corresponding field structure declaration would be as follows:
Field := New(PField, Init(Name, ftString, 50, 0));
if (Field <> nil)
then FieldStructure^.Insert(Field)
else Halt;
end;
AddressFieldStructure := FieldStructure;
end;
The ctFields unit declares many NewXXXXField functions for simplifying the field declaration process.
Ownership of the field structure passed to TTable.Init is conditional. If the initialization is successful, the field structure is used within the table and destructed by the table. If the table's initialization fails, the field structure is not destructed. This is so that the calling program can let the end user attempt to correct the problem without having to redefine the field structure. If initialization fails, don't forget to dispose of the field structure if it is no longer needed.
Once the field structure has been defined, you must decide where to store the data. Tables may be stored on any read/write stream, regardless of its location (disk, memory, remote, etc.). Tables themselves provide no buffering of data items. Buffering is left to the stream. Using a stream with a buffer size which is several times the size of a data item (recommended) provides excellent performance. The stream passed to TTable.Init is not owned by the stream and must always be disposed when use of the stream is finished. This allows tables to be placed anywhere on a stream. The first byte of the table is stored at the current position in the stream when the stream is passed to a table's Init constructor.
Initializing a table
Once the field structure and stream type have been declared, you are now ready to initialize the table.
To open a table which was previously created, simply declare the stream using stOpen as the file mode. Be sure not to use the stCreate constant, as this will erase all data held in the stream. Then just pass the newly instantiated stream to the Open constructor (rather than Init) and that's it! For example:
var
Stream: PBufStream;
Table: PTable;
begin
Stream := New(PBufStream, Init(TempFile, stOpen,
BufferSize));
if Stream = nil then
Halt;
Table := New(PTable, Open(Stream));
if Table = nil then
begin
Dispose(Stream, Done);
Halt;
end;
Dispose(Table, Done);
end;
Data Management in Tables
Inserting new data items into a table is as inserting items into any other container: it is done through the Insert method. By default, all inserted data items are placed at the end of the table, causing the stream to grow. Retrieving data items is done as in any other sequence, by using the At method. Finally, to update an existing item, simply call AtPut with the updated record information.
In addition to the standard data retrieval and updating methods of a sequence, TTable offers several methods that will let you retrieve and update individual fields (AtField and AtPutField), find the name or length of a field (FieldName and FieldLength), the number of decimals in a field (FieldDecimals), the number of fields in a row (FieldCount), etc. The beginning of a field in the data item is determined by a combination of the field type and size parameters in the table's field structure.
If a record contains pointers to data, such as a PString, and you intend to use the field access methods of a table, you must override TTable.FieldOffset to give the correct information. Also, AtField and AtPutField will need to overridden for correct field processing and FreeItem, GetItem and PutItem to ensure proper data handling.
As with any container, all data items retrieved from a table should be disposed using DoneItem. Since tables are stream based data storage structures, new pointers are allocated by At. Failing to call DoneItem when you are finished with the pointer will result in a memory leak.
Object tables
TTable only can store variables which are a simple type or a record structure. TObjectTable provides a mechanism for storing any object which is a descendant of TObject. You must remember to register each object type which will be stored in the table for stream registration using RegisterType. Failing to do so causes a run-time error. There are a few minor differences between object and non-object tables.
The first difference is in the field structure declaration. The data area in a stream for an object must be large enough to hold the object with each field at its maximum length. In other words, if the object has a field which is a PString, the field structure must reserve enough space to store the string in its maximum length. This results in potentially minor wasted stream resources, but is better than always writing to the end of the stream to prevent overwriting data following the object.
Using an object-oriented version of the previous example (see TABLE2.PAS), the object type and field structure declaration would be declared as follows:
type
Str50: string[50];
PMyObject = ^TMyObject;
TMyObject = object(TObject)
Line1: PString;
Line2: PString;
City: PString;
State: PString;
constructor Init (ALine1, ALine2, ACity,
AState: Str50);
constructor Load (var S: TStream);
destructor Done; virtual;
procedure Store (var S: TStream); virtual;
end;
var
Structure: PFieldStructure;
Field: PField;
begin
Structure := New(PFieldStructure, Init(4, 1));
if (Structure <> nil) then
for i := 1 to 4 do
begin
case i of
1: Name := 'Line1';
2: Name := 'Line2';
3: Name := 'City';
4: Name := 'State';
end;
Field := NewPStringField(Name, 50);
if (Field <> nil)
then FieldStructure^.Insert(Field)
else Halt;
end;
end;
All tables which store objects and will use field access to data must override AtField, AtPutField, and FieldOffset because of the internal variation in field position within objects. The fields may be pointers themselves, but the field offset is also affected by the levels of inheritance for the object.
Other than these minor differences, the use of a TObjectTable is identical to a TTable.
